Inside Macintosh: 3D Graphics Programming With QuickDraw 3D /

Chapter 2 - 3D Viewer

Using the 3D Viewer

This section provides examples of how to use the 3D Viewer to display 3D data in a window.

Checking for the 3D Viewer

Before calling any 3D Viewer routines, you need to verify that the 3D Viewer software is available in the current operating environment. On the Macintosh Operating System, you can verify that the 3D Viewer is available by calling the MyEnvironmentHas3DViewer function defined in Listing 2-1.

Listing 2-1 Determining whether the 3D Viewer is available

Boolean MyEnvironmentHas3DViewer (void)
{
   return((Boolean)Q3ViewerNew != kUnresolvedSymbolAddress);
}

The MyEnvironmentHas3DViewer function checks whether the address of the Q3ViewerNew function has been resolved. If it hasn't been resolved (that is, if the Code Fragment Manager couldn't find the 3D Viewer shared library when launching your application), MyEnvironmentHas3DViewer returns the value FALSE to its caller. Otherwise, if the address of the Q3ViewerNew function was successfully resolved, MyEnvironmentHas3DViewer returns TRUE.

Note

For the function MyEnvironmentHas3DViewer to work properly, you must establish soft links (also called weak links) between your application and the 3D Viewer shared library. For information on soft links, see the book Inside Macintosh: PowerPC System Software. For specific information on establishing soft links, see the documentation for your software development system.

On the Macintosh Operating System, you can verify that the 3D Viewer is available in the current operating environment by calling the Gestalt function with the gestaltQuickDraw3DViewer selector. Gestalt returns a long word whose value indicates the availability of the 3D Viewer. Currently these values are defined:

enum {
   gestaltQuickDraw3DViewer         = 'q3vc',
   gestaltQ3ViewerNotAvailable      = 0,
   gestaltQ3ViewerAvailable         = 1
}

You should ensure that the value gestaltQ3ViewerAvailable is returned before calling any 3D Viewer routines.

Note

For more information on the Gestalt function, see Inside Macintosh: Operating System Utilities.

Creating a Viewer

You can create a viewer object by calling the Q3ViewerNew function. You pass Q3ViewerNew a pointer to the window in which you want the viewer to appear, the rectangle that is to contain the viewer pane, and a selector indicating which viewer features to enable. Q3ViewerNew returns a reference to a viewer object. Listing 2-2 illustrates one way to call Q3ViewerNew. The function MyCreateViewer defined in Listing 2-2 creates a viewer pane that occupies the entire content region of the window whose address is passed to it as a parameter.

Listing 2-2 Creating a viewer object

TQ3ViewerObject MyCreateViewer (WindowPtr myWindow)
{
   TQ3ViewerObject   myViewer;
   Rect              myRect;
   
   /*Get rectangle enclosing the window's content region.*/
   myRect = myWindow->portRect;
   if (EmptyRect(&myRect))    /*make sure we got a nonempty rect*/
      goto bail;

   /*Create a new viewer object in entire content region.*/
   myViewer = Q3ViewerNew((CGrafPtr)myWindow, &myRect, kQ3ViewerDefault);
   if (myViewer == NULL)
      goto bail;

   return (myViewer);         /*return new viewer object*/

bail:
   /*If any of the above failed, return an empty viewer object.*/
   return (NULL);
}

The third parameter to the call to Q3ViewerNew is a set of viewer flags that specify information about the appearance and behavior of the new viewer object. In Listing 2-2, the viewer flag parameter is set to the value kQ3ViewerDefault, indicating that the default values of the viewer flags are to be used. See "Viewer Flags," beginning on page 2-12 for a complete description of the available viewer flags.

Attaching Data to a Viewer

You specify the 3D model to be displayed in a viewer pane's picture area by calling either the Q3ViewerUseFile or Q3ViewerUseData function. Q3ViewerUseFile takes a reference to an existing viewer object and a file reference number of an open metafile, as follows:

myErr = Q3ViewerUseFile(myViewer, myFsRefNum);

You use the Q3ViewerUseData function to specify a 3D model whose data is already in memory (either on the Clipboard or elsewhere in RAM). Q3ViewerUseData takes a reference to an existing viewer object, a pointer to the metafile data in RAM, and the number of bytes occupied by that data. Here's an example of calling Q3ViewerUseData:

myErr = Q3ViewerUseData(myViewer, myDataPtr, myDataSize);

IMPORTANT

The data in the buffer whose address and size you pass to Q3ViewerUseData must be in the QuickDraw 3D Object Metafile format.

Once you attach the metafile data to a visible viewer object, the user is able to see the 3D model in the viewer pane. If, however, the viewer pane was invisible when it was created, you need to call the Q3ViewerDraw function to make it visible.

The 3D Viewer treats the model data as a single group. You can get a reference to the model data currently displayed in the viewer's picture area by calling the Q3ViewerGetGroup function. You can change that model data by calling the Q3ViewerUseGroup function.

You can also retrieve the view object associated with a viewer object by calling the Q3ViewerGetView function. You can then modify some of the view settings, such as the lights or the camera. If you wish, you can also restore the view settings to their original values by calling the Q3ViewerRestoreView function.

Handling Viewer Events

The final thing you need to do to support the 3D Viewer is to modify your main event loop so that events in the viewer controller strip and in the viewer pane can be handled. You need to add a line like this to your event loop:

isViewerEvent = Q3ViewerEvent(myViewer, myEvent);

The Q3ViewerEvent function determines whether the event specified by the myEvent event record affects the specified viewer object. If so, Q3ViewerEvent handles the event and returns TRUE as it function result. Otherwise, Q3ViewerEvent returns FALSE.